Rand
A Rust library for random number generation.
Rand provides utilities to generate random numbers, to convert them to useful types and distributions, and some randomness-related algorithms.
The core random number generation traits of Rand live in the rand_core crate but are also exposed here; RNG
implementations should prefer to use rand_core
while most other users should
depend on rand
.
Documentation:
Usage
Add this to your Cargo.toml
:
[]
= "0.6"
To get started using Rand, see The Book.
Versions
The Rand lib is not yet stable, however we are careful to limit breaking changes and warn via deprecation wherever possible. Patch versions never introduce breaking changes. The following minor versions are supported:
- Version 0.6 was released in November 2018, redesigning the
seq
module, moving most PRNGs to external crates, and many small changes. - Version 0.5 was released in May 2018, as a major reorganisation
(introducing
RngCore
andrand_core
, and deprecatingRand
and the previous distribution traits). - Version 0.4 was released in December 2017, but contained almost no breaking changes from the 0.3 series.
A detailed changelog is available.
When upgrading to the next minor series (especially 0.4 → 0.5), we recommend reading the Upgrade Guide.
Rust version requirements
Since version 0.5, Rand requires Rustc version 1.22 or greater. Rand 0.4 and 0.3 (since approx. June 2017) require Rustc version 1.15 or greater. Subsets of the Rand code may work with older Rust versions, but this is not supported.
Travis CI always has a build with a pinned version of Rustc matching the oldest supported Rust release. The current policy is that this can be updated in any Rand release if required, but the change must be noted in the changelog.
To avoid bumping the required version unnecessarily, we use a build.rs
script
to auto-detect the compiler version and enable certain features or change code
paths automatically. Since this makes it easy to unintentionally make use of
features requiring a more recent Rust version, we recommend testing with a
pinned version of Rustc if you require compatibility with a specific version.
Crate Features
Rand is built with only the std
feature enabled by default. The following
optional features are available:
alloc
can be used instead ofstd
to provideVec
andBox
.log
enables some logging via thelog
crate.nightly
enables all unstable features (simd_support
).serde1
enables serialization for some types, via Serde version 1.simd_support
enables uniform sampling of SIMD types (integers and floats).stdweb
enables support forOsRng
onwasm32-unknown-unknown
viastdweb
combined withcargo-web
.wasm-bindgen
enables support forOsRng
onwasm32-unknown-unknown
viawasm-bindgen
no_std
mode is activated by setting default-features = false
; this removes
functionality depending on std
:
thread_rng()
, andrandom()
are not available, as they require thread-local storage and an entropy source.OsRng
andEntropyRng
are unavailable.JitterRng
code is still present, but a nanosecond timer must be provided viaJitterRng::new_with_timer
- Since no external entropy is available, it is not possible to create
generators with fresh seeds using the
FromEntropy
trait (user must provide a seed). - Several non-linear distributions distributions are unavailable since
exp
andlog
functions are not provided incore
. - Large parts of the
seq
-uence module are unavailable, unless thealloc
feature is used (several APIs and many implementations requireVec
).
License
Rand is distributed under the terms of both the MIT license and the Apache License (Version 2.0).
See LICENSE-APACHE and LICENSE-MIT, and COPYRIGHT for details.